Before you begin the installation, make sure that you have reviewed the system requirements (see System Requirements), completed the prerequisites (see Planning & Preparing), and have your Keyfactor Command license file ready to upload during the configuration.
The following installation steps show all possible Keyfactor Command features enabled. Your Keyfactor Command license may not cover all Keyfactor Command features. If it does not, unlicensed features will not be shown in the configuration wizard. You may skip those configuration steps.
To begin the Keyfactor Command installation, execute the KeyfactorPlatform.msi file from the Keyfactor Command installation media and install as follows.
-
On the first installation page, click Next to begin the setup wizard.
Figure 533: Install: Begin Setup Wizard
- On the next page, read and accept the license agreement and click Next. Click Print to review a printed copy if desired.
-
On the next page, select the components to install. For a server with the default roles collocated, leave the default options and click Next to continue. If desired, you can highlight Keyfactor Command and click Browse to select an alternate installation location for the files. The default installation location is:
C:\Program Files\Keyfactor\Keyfactor Platform\Note: Although Figure 534: Install: Select Components shows only the default components selected, the remainder of this page covers configuring Keyfactor Command as though all the components have been selected.
Figure 534: Install: Select Components
Tip: Refer to Keyfactor Command Server(s) for a description of these components.Table 880: Available components for Keyfactor Command.
Component Description Management Portal Mandatory. Web-based management console for configuring all aspects of Keyfactor Command. The Keyfactor API will be installed with this component. Windows Services Mandatory. Includes the timer Windows service to manage timed events, such as CA Sync, PKI monitoring and system maintenance. Web API Optional. The Keyfactor API component. This allows the Keyfactor API for external use to be installed on a separate server from the Management Portal, if desired. Orchestrator Services API Optional. Only required if agents or orchestrators will be used in conjunction with Keyfactor Command. Web based orchestrator services API. CA Connector API Optional. Only required if remote CA clients will be used. Web based CA connector API. This component is disabled by default.
Important: This component requires an instance of RabbitMQ (https://www.rabbitmq.com) to complete the communication from Keyfactor Command to Remote CA Connectors and remote CAs (though RabbitMQ only communicates directly to Keyfactor Command, not the Remote CA Connectors). In many cases, this would be a containerized instance. For example:The component uses OAuth for authentication even if you've opted to use Active Directory authentication for the remainder of your Keyfactor Command installation, and therefore requires an OAuth 2.0 compliant implementation. You may choose to install Keyfactor Identity Provider if you do not have an alternate provider (see Installing Keyfactor Identity Provider).
- On the next screen, click Install.
- On the final installation wizard page, leave the Launch the Configuration Wizard now box selected and click Finish. The configuration wizard should start automatically. This can take several seconds.
-
On the Keyfactor Command Database Configuration page, enter the name, IP address, or fully qualified domain name (FQDN) of your SQL server and select a Credential Type of either Windows or SQL.
Important: Keyfactor Command uses an encrypted channel to connect to the SQL server by default, which requires configuration of an SSL
TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. certificate on the SQL server (see Using SSL to Connect to SQL Server). The name or IP address you enter here for your SQL server must be available as a SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. in this certificate unless you have disabled the encrypted connection for Keyfactor Command (see Configurable SQL Connection Strings).-
If you select Windows as the Credential Type for connecting to SQL, click the Connect button.
Figure 535: Windows Authentication
-
If you select SQL as the Credential Type for connecting to SQL, the window will expand to include fields to enter a SQL username and password. Enter a username and password to authenticate to SQL, and click the Connect button.
Note: The password must not contain single or double quotes. An error will be shown if single or double quotes are used in the password.
Figure 536: SQL Authentication
Note: For the permissions required for this user, see Grant Permissions in SQL.Note: Keyfactor Command supports configuration of a base SQL connection template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. that is used for all connections Keyfactor Command makes to SQL. For more information, see Configurable SQL Connection Strings.Note: Your SQL server must be configured to support mixed mode authentication in order to use the SQL option. -
-
After the Connect button is clicked, the database name field will be activated. You can either enter the name of the desired database—for either a new or existing database—or click Browse to scroll through a list of existing databases.
Note: On subsequent runs of the configuration wizard, the database name field will be pre-populated with the database name used on the last completed run. Any change to the server connection fields (server name, authentication type, etc.) will require the Connect button to be used again to unlock the database name field and the Continue button. -
Click the Continue button. You will receive a confirmation dialog if any changes will be made to the database at this stage.
Note: If any of the following situations occurs, you will receive a message:- The selected database does not exist and will be created.
- The selected database is empty and not associated with Keyfactor Command; it will be populated with the Keyfactor Command schema.
- The selected database does not match the current product schema and will be upgraded.
- The selected database is not empty and is not associated with Keyfactor Command.
- The user does not have access to the database.
- An SSL certificate is not correctly configured on the SQL server.
-
On the Keyfactor Command Encryption Warning page, read and understand the warning. Make note of the referenced documents to provide to your SQL team. Take advantage of the option to make a backup of the Database Master Key (DMK) by entering a path to a directory on your SQL server along with a filename for the backup file and a password to encrypt the file and clicking Backup. The user running the Keyfactor Command installer must have write permissions to this directory. Click Continue.
Important: Keyfactor Command uses Microsoft SQL Server encryption to protect security sensitive data, including service account credentials. Backup of the SQL server Database Master Key (DMK) is of critical importance in database backup and recovery operations. The backup file of the DMK and the password should be stored in a safe, well-documented location. Without the file and password created with this process, some data that is encrypted within the Keyfactor Command database will be unrecoverable in a disaster recovery scenario.If you choose to install Keyfactor Command in the default location, the referenced documents can later be found here:
C:\Program Files\Keyfactor\Keyfactor Platform\Configuration\DMKBackup.docxC:\Program Files\Keyfactor\Keyfactor Platform\Configuration\DMKRestore.docx
Figure 537: Configure: Backup Database Master Key
-
On the Keyfactor Command License upload page, click Upload and browse to locate the license file provided to you by Keyfactor. This file should have the extension CMSLICENSE. Once the uploaded license shows as valid, click Continue.
Figure 538: Configure: Upload License
-
In the Keyfactor Command configuration wizard, you can choose to upload a configuration file to populate the fields. You may have a file saved from a previous run of the configuration wizard or you may be provided one by Keyfactor. To upload a file, in the configuration wizard, click File at the top of the wizard and choose Open Data File. Browse to locate the configuration file. Configuration files have an extension of .cmscfg. The file may be protected with a password. If it is, you will need to provide this password to open the file. Continue with the remainder of the steps, reviewing the tabs to assure that the data is complete and correct.
Note: If you open a configuration file that contains configuration information for an identity provider other than Active Directory but does not set OAuth enabled to true, the additional identity provider information will not be loaded.
Figure 539: Configure: Open Data File
Note: At the bottom of the configuration wizard, if the database server name is longer than will fit in the provided window, it will be truncated and an ellipsis will be added. -
A separate application pool is required for each virtual directory that will be created for Keyfactor Command in IIS. If you’ve chosen to install all the Keyfactor Command components, this will be five application pools for the virtual directories with the following names, by default:
-
KeyfactorAgents (Keyfactor Command agent and orchestrator
Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. service endpoint An endpoint is a URL that enables the API to gain access to resources on a server.) -
KeyfactorAnalysis (Keyfactor Command dashboard and reporting)
-
KeyfactorProxy (Authentication for an identity provider other than Active Directory)
-
KeyfactorPortal (Keyfactor Command Management Portal)
On the Application Pools tab of the configuration wizard, click Add, change the default application pool name, if desired, and enter the user name (DOMAIN\username format) and password of the Active Directory service account under which the application pool will run. You may use the people picker button (
) to browse for the account. Click the verify button (
) to confirm that the username and password entered are valid. Assuming the verification completes successfully, click Save.Tip: The same service account may be used for all application pools.
Figure 540: Configure: Application Pools
-
-
Important: Before migrating an existing implementation from Active Directory to OAuth or vice versa, please see Migrating to a New Identity Provider.
On the Authentication tab of the configuration wizard, check the Use OAuth for Keyfactor Portal, API, and Orchestrators box if you wish to use one or more OAuth identity providers as either a direct identity provider or a federation gateway to another identity provider. If you do not select this, you will be using the default identity provider of Microsoft Active Directory. If you checked OAuth, configure it as follows. If you opted to install the CA Connector API component, the Use OAuth for CA Connector API box will be shown checked and grayed out. This box cannot be unchecked. OAuth authentication is required for the CA Connector API. If either OAuth box is checked, configure OAuth as follows. If only the Use OAuth for CA Connector API box is checked, the remainder if the top section, the Claims Proxy section, and the Identity Provider Token Credentials section will be grayed out. Skip to the Identity Provider section for configuration.
Important: Only one type of identity provider (Active Directory or OAuth) may be configured at a time on each Keyfactor Command instance.On the Authentication tab in the top section, accept the defaults for the Session Expiration and Cookie Expiration or modify these if appropriate for your environment. The Session Expiration value determines the length of time a browser session in the Keyfactor Command Management Portal will remain logged in before the user is prompted to re-authenticate regardless of whether the session is idle or in active use. The Cookie Expiration value determines the length of time the authentication cookie
Note: For Keyfactor Identity Provider, these values should match those configured for the SSO Session Max and Access Token Lifespan in Keyfactor Identity Provider (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). If you’ve opted not to issue refresh tokens in Keyfactor Identity Provider, the Cookie Expiration value should match the Session Expiration value.Select an OAuth identity provider in the Default Login dropdown. This dropdown will only be populated once you add at least one identity provider in the identity providers section and enter values in the provider’s Authentication Scheme (reference name) and Display Name fields. The default login applies to users attempting to access Keyfactor Command who do not provide an Identity Provider Hint in the request URL to be directed to a specific identity provider for authentication. If you have only one identity provider, set the default login to this identity provider. If you have multiple identity providers, you may wish to set the default login to the most heavily used identity provider and provide users of other identity providers a URL complete with identity provider hint.
Tip: An identity provider hint given in the Keyfactor Command URL contains the specific identity provider referenced by Authentication Scheme. For example:https://keyfactor.keyexample.com/KeyfactorPoral/Login/Signin?idpHint=Command-OIDC-3Where keyfactor.keyexample.com is the fully qualified domain name of the Keyfactor Command server, KeyfactorPortal is the virtual directory for the Management Portal on that server, and Command-OIDC-3 is the authentication scheme for the identity provider to use for authentication.
Claims Proxy Section
On the Authentication tab in the Claims Proxy section, enter the FQDN that you will use to access the Keyfactor CommandManagement Portal in the Host Name field. This can be either the actual host name
The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). of the server on which you are installing the Keyfactor Command Administration component or a DNS The Domain Name System is a service that translates names into IP addresses. alias pointing to the server. If you have multiple Keyfactor CommandManagement Portal servers with load balancing, this will be a DNS name pointing to your load balancer. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown.Note: When you install Keyfactor Command using an OAuth identity provider, a virtual directory called, by default, KeyfactorProxy is created in IIS for OAuth authentication. If you later disable OAuth, this virtual directory will still exist. This virtual directory is not used if you opt to use Active Directory as an identity provider. During Keyfactor Command uninstallation it will be removed, or you may opt to remove it manually if you are switching from OAuth to Active Directory for authentication.
Figure 541: Configure: Identity Providers—OAuth Claims Proxy Section
Tip: There is no Use SSL check box for this component because SSL is required.Identity Provider Section
On the Authentication tab in the Identity Provider section, click Add to create a new identity provider. You may create more than one OAuth identity provider, any of which may be used to authenticate to Keyfactor Command (so users from OAuth IdP A and users from OAuth IdP B may both access Keyfactor Command). Active Directory may not be configured in conjunction with any OAuth identity providers and you may use only one Active Directory identity provider. Select the identity provider currently being edited in the Identity Provider dropdown.
Note: The Remove button can only be used to remove identity providers newly added in the configuration wizard. Once an identity provider has been saved to the Keyfactor Command database (by completing the configuration wizard), the remove option will be grayed out for it.In the Identity Provider Parameters section, enter an Authentication Scheme (reference name) and Display Name for the current identity provider. The Authentication Scheme should be entered without spaces. This is used in constructing URLs that reference the identity provider from Keyfactor Command. In the Type dropdown, select an appropriate type for your identity provider. Most identity providers can be supported with the Generic type. For Auth0, select the Auth0 type.
For Keyfactor Identity Provider, the Authentication Scheme you enter here must match the name you used when configuring the redirect URIs for Keyfactor Identity Provider (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).
Populate the identity provider parameters according to Table 881: Identity Provider Parameters. The fields that appear will vary depending on the selected Type. HTTPS is required for URL parameters. For more information about identity providers, see Selecting an Identity Provider for Keyfactor Command.
Figure 542: Configure: Identity Providers—OAuth Identity Provider Section for Type Generic
Note: If you return to the configuration wizard and re-run it to add a new identity provider or change the identity provider that’s in active use for the system, you should restart the web server services (run an iisreset) after making the change to clear any cached data. If you’re using more than one Keyfactor Command server in a cluster configuration, the web server services should be restarted on all of them.Table 881: Identity Provider Parameters
Name Type Example Description
1 - String Command- OIDC- Client The audience value for the identity provider.
For Keyfactor Identity Provider, this should be set to the same value as the Client Id. For example:
Command- OIDC- ClientThis parameter is required.
1 - String The unique identifier defined in Auth0 or a similar identity provider for the API.
This parameter only appears if Auth0 is selected as the type and is required in that case.
Authority 1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor The issuer/authority endpoint URL for the identity provider.
For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
This parameter is required.
Tip: When you add or update an identity provider, the provider’s discovery document is validated based on this authority URL. The discovery document is also validated periodically in the background. The following are validated:That the discovery document is reachable using the Authority value provided and can be parsed into a valid discovery document.
That the Authority URL matches the Issuer returned in the discovery document.
That all the URLs on the discovery document are using HTTPS.
That the JSONWebKeySetUri value is included on the discovery document.
That any endpoint configuration values (Authorization Endpoint, Token Endpoint, UserInfo Endpoint, JSONWebKeySetUri) that have been saved or are being saved match—including case—the values returned in the discovery document. The UserInfo Endpoint is not a required configuration field, but if a value is provided, it must match what’s in the discovery document.
If any of these validation tests fail, any identity provider changes in process will not be saved and an error will be displayed or logged.
1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /auth The authorization endpoint URL for the identity provider.
For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
This parameter is required.
1 - String Command- OIDC- Client The ID of the client application created in the identity provider for primary application use.
For Keyfactor Identity Provider, this should be:
Command- OIDC- ClientFor more information, see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation).
This parameter is required.
2 - Secret The secret for the client application created in the identity provider for primary application use.
For Keyfactor Identity Provider, see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation for help locating this. It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
Supported methods to store secret information are:
-
Store the secret information in the Keyfactor secrets table.
A Keyfactor secret is a user-defined username or password that is encrypted and stored securely in the Keyfactor Command database.
-
Load the secret information from a PAM provider.
See Privileged Access Management (PAM) for more information.
This parameter is required.
1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /.well-known /openid-configuration The discovery URL for the identity provider.
For Keyfactor Identity Provider, this is the link to the OpenID Endpoint Configuration page, which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). Populate this value and click Fetch to populate the remainder of the fields in this section, if desired.
If you opt not to populate this field or if the discovery document does not return a valid response, the remainder of the fields in this section of the configuration will need to be configured manually. This value is not stored in the database.
This field does not appear in the Management Portal identity provider configuration.
1 - String cid A backup value used to reference the type of claim used for users in the identity provider in case the primary referenced name does not contain a value. This parameter is required.
1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs The JWKS (JSON Web Key Set) URL for the identity provider.
For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
This parameter is required.
1 - String preferred_ username The name used to reference the type of user claim for the identity provider.
For Keyfactor Identity Provider, this should be:
preferred_ usernameThis parameter is required.
1 - String groups The value used to reference the type of group claim for the identity provider.
For Keyfactor Identity Provider, this should be:
groupsThis parameter is required.
1 - String One or more scopes that are requested during the OIDC protocol when Keyfactor Command is the relying party. Multiple scopes should be separated by spaces.
This value is not used for Keyfactor Identity Provider.
1 -String https:// my-auth0-instance .us.auth0.com /oidc/logout The signout URL for the identity provider.
This parameter only appears if Auth0 is selected as the type and is required in that case.
Timeout 1 - String 60 The number of seconds a request to the identity provider is allowed to process before timing out with an error. 1 - String An audience value to be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client.
This value is not used for Keyfactor Identity Provider.
1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /token The token endpoint URL for the identity provider.
For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
This parameter is required.
1 - String One or more scopes that should be included in token requests delivered to the identity provider when making a token request where Keyfactor Command is acting as the OAuth client. Multiple scopes should be separated by spaces.
This value is not used for Keyfactor Identity Provider.
1 - String sub The value used to reference the type of claim used for users in the identity provider. For Keyfactor Identity Provider, this should be (for subject): subThis parameter is required.
1 - String https:// my-keyidp-server .keyexample.com /realms /Keyfactor /protocol /openid-connect /certs The user info endpoint URL for the identity provider.
For Keyfactor Identity Provider, this is included among the information that can be found on the OpenID Endpoint Configuration page, a link to which can be found on the Realm Settings page (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). It is automatically returned by the Discovery Document Endpoint Fetch step. Review it to confirm that it appears correct.
Identity Provider Token Credentials Section
On the Authentication tab in the Identity Provider Token Credentials section, enter a Client Id and Client Secret for a service account you have created in one of your identity providers to allow Keyfactor Command to make API requests to itself. Select the appropriate identity provider for the account in the Identity Provider Name dropdown. This does no need to be the default identity provider. These values are required. Enter values in the Token Audience and Token Scope fields if necessary for your identity provider. These fields are not used for Keyfactor Identity Provider.
For Keyfactor Identity Provider, this is created as a client (see Service Accounts). Keyfactor recommends that you use a different client for this purpose than the client used for the main connection from Keyfactor Command to the identity provider (see Client Id in Table 881: Identity Provider Parameters).
Figure 543: Configure: Identity Providers—OAuth Identity Provider Token Credentials Section
-
On the Database tab in the top section, select an Authentication Mode for ongoing communications to SQL server—Windows Authentication or SQL Server Authentications. Your SQL server must be configured to support mixed mode authentication in order to use the SQL server authentication option.
-
If you select Windows Authentication, login(s) will be created in SQL for the application pool user(s) you created on the Application Pools tab and granted appropriate permissions (other than the application pool for the Logi Analytics Platform, which does not need database access).
-
If you choose SQL server authentication, enter a User and Password of a SQL administrator for the Keyfactor Command SQL database. If the user does not exist in SQL, it will be created and granted the necessary permissions for management of the Keyfactor Command database. If the user already exists in SQL, it will be granted the necessary permissions. If the database you originally connected to is an Azure database, SQL Server Authentication is the only option provided.
For more information, see Grant Permissions in SQL.
Encryption Section
If desired, check the Configure Encryption box. This option allows you to encrypt select sensitive data stored in the Keyfactor Command database using a separate encryption methodology utilizing a Keyfactor Command-defined certificate on top of the SQL server encryption noted above. This additional layer of encryption protects the data in cases where the SQL Server master keys cannot be adequately protected. Read and understand the encryption warning. This warning applies to implementations with more than one Keyfactor Command server.
Note: In an environment where there are multiple copies of Keyfactor Command pointing to the same database, each server running a Keyfactor Command instance will need to have the same encryption certificate AND the corresponding private key Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure..Select Application and SQL for the Encryption Type and click the Select button to choose a certificate from the Personal Certificate store of the Local Computer with which to encrypt the data. Only valid certificates with the appropriate key usage will appear in the selection dialog. See Acquire a Public Key Certificate for the Keyfactor Command Server.
If you enable application-level encryption, your certificate must either be using a key storage provider (KSP) or you must manually grant permissions to the certificate’s private key (see Application-Level Encryption).
Tip: If you need to reset the encryption level to remove application-level encryption, run the configuration wizard again and select the SQL Only option. You must ensure that the server you are re-running the configuration wizard on has both the certificate used for application-level encryption and its associated private key. When Keyfactor Command notices that application-level encryption has been disabled, it will process all the secrets in the database and remove the additional encryption. The data will then be re-saved to the secrets table using only SQL-level encryption.
Figure 544: Configure: Encryption Warning
Figure 545: Configure: Database Tab
-
-
On the Service tab, enter the user name and password of the Active Directory (DOMAIN\username format) or local (HOSTNAME
The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername).\username format) service account under which the Keyfactor Command Service will run. This can be the same service account used for the application pool(s) or a different service account. You may use the people picker button () to browse for the account. Click the verify button () to confirm that the username and password entered are valid. If desired, check the Start service on bootup box to start the Keyfactor Command Service at system start.Tip: Checking Start service on bootup sets all jobs of type TimerService to true in the Keyfactor Command service appsettings.json file. These settings can be modified on a job-by-job basis in this appsettings.json file -
Email Tab
On the Email tab, enter the FQDN of your SMTP
Short for simple mail transfer protocol, SMTP is a protocol for sending email messages between servers. server, the SMTP port (default is 25), and the sender name and account. Depending on the email configuration in your environment, the sender account may need to be a valid user on your mail server (using Active Directory credentials) or you may be able to put anything in this field (if your mail server supports anonymous connections). You may use the people picker button () to browse for the sender account if you are using a valid account. Select the Use SSL box if this option is supported by your mail server and select the appropriate authentication method for your environment. If your mail server requires that you provide a username and password for a valid user, enter that Active Directory username and password in the fields at the bottom of the page after selecting the Explicit credentials radio button. You may use the people picker button () to browse for the account. Click the verify button () to confirm that the username and password entered are valid. The user you select here must match the email address you set in the Sender Account field if you select Explicit credentials. The information entered on this tab may later be changed in the Keyfactor Command Management Portal.
Figure 547: Configure: Email Tab
-
On the Keyfactor Portal tab in the top section, enter the FQDN that you will use to access the Keyfactor Command Management Portal in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Administration component or a DNS alias pointing to the server. If you have multiple Keyfactor Command Management Portal servers with load balancing, this will be a DNS name pointing to your load balancer. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Enrollment Section
In the Enrollment
Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). section of the page, modify the default Certificate Subject Format field, if desired. The subject values provided in this field are substituted at processing time for any entered by the user in PFX A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. enrollment or provided with enrollment defaults if the template used is set to supply in request.The data in the subject format takes precedence over any data entered during PFX enrollment or supplied by enrollment defaults
CN={CN},E={E},O=Key Example\, Inc.,OU={OU},L=Chicago,ST=IL,C=USThe organization for certificates generated through PFX enrollment will always be Key Example, Inc. regardless of what is shown on the PFX enrollment page during enrollment.
This setting also applies to CSRs generated using the CSR
A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. generation method.Data from the default subject does not display in the PFX enrollment form. To define defaults that will display in the PFX enrollment form (and can be modified by users), use enrollment defaults
Note: Backslashes are required before any commas embedded within values in the subject field (e.g. O=Key Example\, Inc.). Quotation marks should not be used in the strings in the fields except in the case where these are part of the desired subject value, as they are processed as literal values.Tip: The default subject format does not apply to enrollments done using the CSR enrollment method or any requests done with the Keyfactor API.PFX Enrollment Section
In the PFX Enrollment section of the page, select the Domain radio button if you wish PFX files to be protected with the user’s Active Directory password or select the Auto-Generated radio button if you wish PFX files to be protected with a one-time password. Check the Alphanumeric Password Characters box if you wish the one-time password used to protect PFX files to contain numbers and letters. Uncheck the Alphanumeric Password Characters box if you wish the one-time password used to protect PFX files to contain numbers, letters and special characters. In the Password Length field, enter a number for the number of characters the one-time password should have. The minimum value is 8. If you select the Domain radio button, the data entered in the password fields is not relevant.
Figure 548: Configure: Keyfactor Portal Tab
-
On the Administrative Users tab, click Add to add users or groups that you will use to control administrative access to the Keyfactor Command Management Portal.
Enter only the users and/or group(s) to which you want to grant full administrative rights to the Keyfactor Command Management Portal. Following initial configuration, you can create other permission levels and grant those permission levels to other users or groups through the Keyfactor Command Management Portal.
Users and Groups for Active Directory as an Identity Provider
For each user to be added:
-
In the Identity Provider dropdown, select Active Directory.
-
In the Claim Type dropdown, select ADUser for a user account or ADGroup for a group created in Active Directory.
-
In the Claim Value field enter the user or group name for the account in DOMAIN\name format (e.g. KEYEXAMPLE\Keyfactor Administrators).
-
In the Description field enter a description to help you identify the user or group (e.g. the user’s name).
Important: The built-in Active Directory groups Domain Admins and Enterprise Admins cannot be used directly to grant access to the Management Portal due to how these groups function within Windows. You can create a custom Active Directory group, reference that group in the Management Portal, and add the built-in Domain Admins or Enterprise Admins group to that custom group, if desired.Important: For environments using Active Directory as an identity provider, the administrative group must be created as a Global or Universal group. If the administrative group is created as a domain-local group, it will not be recognized by the Management Portal Security Roles and Identities configuration. Configuration of the Management Portal will be incomplete until the group is deleted and recreated as a Global or Universal group.
Figure 549: Configure: Administrative Users Tab for Active Directory as an Identity Provider
Users for OAuth Identity Providers
For each user to be added:
-
In the Identity Provider dropdown, select the display name of the identity provider you created on the Authentication tab.
-
In the Claim Type dropdown, select OAuthSubject for a user account created in your OAuth identity provider, OAuthRole for a role created in your OAuth identity provider, or OAuthClientId for a client application created in your OAuth identity provider. If your claim doesn’t fall into one of these categories, select OAuthOid.
-
In the Claim Value field enter the GUID for the user account, role name for the role, or client ID for the client (see Configuring Keyfactor Identity Provider and Collecting Data for the Keyfactor Command Installation). If you selected OAuthOid, enter an appropriate ID to identify the claim.
-
In the Description field enter a description to help you identify the user (e.g. the user or group name).
Figure 550: Configure: Administrative Users Tab for OAuth as an Identity Provider
-
-
On the Dashboard and Reports tab, enter the FQDN of the server hosting the Keyfactor Command Management Portal—where the Logi Analytics Platform is installed—in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Management Portal component or a DNS alias pointing to the server. Check or uncheck the Use SSL box as appropriate for your environment. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown.
Note: If you are installing the Management Portal in a load balanced configuration, see Appendix - Logi Load Balancing: Keyfactor Command Configuration Wizard Setup.
Figure 551: Configure: Dashboard and Reports Tab
-
On the Orchestrators tab, enter the FQDN of the server hosting the Keyfactor Command orchestrators web site in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Services (Orchestrator Services API) components or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Reenrollment Section (Optional)
In the Template For Submitted CSRs field, from the dropdown, select the template to be used for reenrollment requests made from the Certificate Stores page.
In the CA For Submitted CSRs field, enter the certificate authority
A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. used for reenrollment requests made from the Certificate Stores page. The CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. should be entered in the format FQDN\Logical Name The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two)..
Figure 552: Configure: Orchestrators Tab
Certificate Authentication Section (Optional)
In the Certificate Authentication section of the Orchestrators tab, check the Enabled box if you wish to support client certificate enrollment from the Keyfactor Universal Orchestrator
The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with servers and devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can provide certificate management capabilities on a variety of platforms and devices (e.g. Amazon Web Services (AWS) resources, Citrix\NetScaler devices, F5 devices, IIS stores, JKS keystores, PEM stores, and PKCS#12 stores) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux servers or Linux containers.. In the Certificate Authentication HTTP Header field, enter the HTTP header appropriate to your client certificate authentication method (see Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication Directly and Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC . In the Certificate Authentication Username and Certificate Authentication Password fields, enter the credentials for the Active Directory user configured to authenticate the orchestrator(s) to the Keyfactor Command server. -
On the API tab, enter the FQDN of the server hosting the Keyfactor Command Keyfactor API service in the Host Name field. This can be either the actual host name of the server on which you are installing the Keyfactor Command Services (Keyfactor API) components or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Figure 553: Configure: API Tab
-
On the CA Connector API tab, enter the FQDN of the server hosting the Keyfactor Command CA Connector API service in the Host Name field. This can be either the actual host name of the server on which you are installing the CA Connector API component or a DNS alias pointing to the server. Select the Default Web Site in the Web Site dropdown, or other web site as desired. Accept the default for the Virtual Directory and select the application pool for this virtual directory that you created earlier in the Application Pool dropdown. Check or uncheck the Use SSL box as appropriate for your environment.
Task Queue Section
In the Task Queue section of the page, enter the following information to provide Keyfactor Command with the necessary information to acquire a token for and then communicate with your instance of RabbitMQ:
-
Task Queue URL
The amqp or amqps URL to the RabbitMQ instance. For example:
amqps://appsrvr12.keyexample.com -
Authentication Type
Select either Username/Password or OAuth Client Credentials. The remaining fields will vary depending on the selection you make here. Keyfactor strongly recommends that if you choose the Username/Password option, you connect to RabbitMQ over a secure channel (amqps).
-
Username/Password Details
If you selected Username/Password, enter a Username and Password valid for authentication to the RabbitMQ instance.
-
OAuth Client Credentials Details
If you selected OAuth Client Credentials, enter the following information:
-
Token URL
Set this to the URL of the token endpoint for your OAuth identity provider. For example:
https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token -
Client ID
The client you created in your OAuth identity provider to authenticate to your RabbitMQ instance. If you’re using Keyfactor Identity Provider, see Service Accounts for help creating a client account.
-
Client Secret
The secret of the client you created in your OAuth identity provider to authenticate to your RabbitMQ instance.
-
Scope
One or more scopes that should be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.
-
Audience
Specify an audience value to be included in token requests delivered to your OAuth identity provider. This is not required when using Keyfactor Identity Provider.
-
Figure 554: Configure: CA Connector API Tab
Tip: While not required for operation, the CA Connector API can use WebSockets as a transport protocol. To leverage WebSockets, it must be installed in IIS. This can be done via Server Manager under Add Roles > Web Server (IIS) > Web Server > Application Development > WebSocket Protocol. If WebSockets are not enabled, HTTP long-polling will be used as the transport protocol. -
-
On the Auditing Configuration tab, enter the number of weeks to retain audit data in the Audit Entry Retention Period (weeks) field. By default, 52 weeks of data is retained.
Note: Configuration wizard files from existing databases will not populate this field upon upgrade to prevent changing the retention period to an potentially unwanted setting. Previous versions of Keyfactor Command set this value in years.The audit log cleanup job runs once daily and removes any audit log entries older than the time specified in the retention parameter
A parameter or argument is a value that is passed into a function in an application. except those in the following protected categories:
-
Security
-
CertificateCollections
-
ApplicationSettings
-
SecurityClaims
-
SecurityRoles
-
IdentityProviders
Linux SysLog Server Section
In the Linux SysLog Server section of the page, check the Connect to SysLog to enable the option to copy audit logs in real time to a separate server for collection
The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). and analysis with a centralized logging solution (e.g. rsyslog Rsyslog is an open-source software utility used on UNIX and Unix-like computer systems for forwarding log messages in an IP network., Splunk, Elastic Stack). In the Host Name field, enter the fully qualified domain name of the server that will be receiving the logs. Set the Port to the port on which your log receipt application is listening to receive the logs. The default value is 514 (the default rsyslog port). If desired, turn on Use TLS SysLogging. When you click Save, Keyfactor Command will verify that a connection can be made to the specified server on the specified port. Additional configuration on both the Keyfactor Command server and log receipt server are needed to make TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. communications work (see Prepare for External Log Shipping over TLS (Optional)). If you have not yet completed these configurations, you will receive a validation error on save if the Use TLS SysLogging option is enabled.Note: Keyfactor Command uses RFC 5424 for syslog messages when using TLS and RFC 3164 when not using TLS.The auditing settings can be updated on the auditing tab of the applications settings page following installation
Figure 555: Configure: Audit Configuration Tab
-
-
At this point in the configuration, if you have populated all the required fields, the yellow warning banner at the top of the configuration wizard should have disappeared. If it is still visible, click the dropdown arrow to open the Warnings page and review the warning(s) to see what needs to be corrected. Under some circumstances you will be allowed to continue with the configuration even if the yellow warning banner is still present. You will know this is the case if the Verify Configuration button is active. Under these circumstances, you should review the warnings before continuing.
Figure 556: Configure: Configuration Warnings
-
Before completing the configuration wizard, you may choose to save a copy of the configuration as a file for future use. To download the configuration as a file, in the configuration wizard, click File at the top of the wizard and choose Save Data File. Browse to a location where you want to save the configuration file, enter a file name and click Save. You will be prompted to enter a password to encrypt the data in the file. You may choose to protect the file with a password or not. If you use a password at this time, you will need to provide this password to open the file. Keyfactor highly recommends using a strong password to protect the file. If you do not wish to use a password to protect the file, sensitive information (e.g. passwords for the service accounts entered in the configuration wizard) will be removed from the file. Once you enter a password or uncheck the encryption box, click OK to save the file.
Important: Keyfactor highly recommends that you use strong passwords for any accounts or certificates related to Keyfactor Command and associated products, especially when these have elevated or administrative access. A strong password has at least 12 characters (more is better) and multiple character classes (lowercase letters, uppercase letters, numeral, and symbols). Ideally, each password would be randomly generated. Avoid password re-use.
Figure 557: Configure: Save Configuration as a File
- At the bottom of the Keyfactor Command Configuration Wizard dialog, click Verify Configuration.
-
On the Configuration Operations page, review the planned operations and then click Apply Configuration. Prior to clicking Apply Configuration, you can revisit any of the Configuration Wizard tabs to review or make changes by clicking Edit Configuration.
Figure 558: Configure: Configuration Operations
-
When the configuration completes successfully, you will see the below message. If you didn’t save a copy of the configuration earlier, you may do so at this time by clicking Save Settings. Otherwise, click Close to close the dialog.
Figure 559: Configure: Configuration Complete
